package org.liang.transfer;


/**
 * 传输器行为接口.
 * 
 * <pre>
 * 包含以下行为：
 *  1.连接（使用默认端口）
 *  2.连接（包含所有信息：主机、端口、用户名、密码）
 *  3.上传文件到服务器.
 *  4.下载远程服务器上的文件，并存储到本地.
 *  5.下载远程服务器上的文件，并存储到本地（支持过滤）.
 *  
 *  使用说明：
 *    1. 调用上传下载之前必须 调用连接，否则会抛出未连接异常
 *    2. 上传完成后需要关闭连接
 * </pre>
 * 
 * @author L.Yang
 * @version v1.0 2016年4月14日 下午2:24:37
 */
public interface Transfer {

    /**
     * 连接FTP.
     * 
     * <pre>
     * 所有对ftp操作之前需执行此方法。
     * 实际操作为连接网络及登录ftp。
     * </pre>
     */
    void connect(String host, int port, String username, String password);

    /**
     * 连接FTP.
     * 
     * <pre>
     * 所有对ftp操作之前需执行此方法。
     * 实际操作为连接网络及登录ftp。
     * </pre>
     */
    void connect(String host, String username, String password);

    /**
     * 上传文件到服务器.
     * 
     * @param remote
     *            远程FTP服务器文件路径
     * @param local
     *            本地存储文件的完整路径（包含文件名）
     */
    void upload(String remote, String local);

    /**
     * 下载远程服务器上的文件，并存储到本地.
     * 
     * <pre>
     * remote 如果是文件夹则将文件夹中的文件全部下载；
     * 如果local 是文件名则使用locl 如果local 是路径则使用服务器文件名；
     * </pre>
     * 
     * @param remote
     *            远程FTP服务器文件的完整路径
     * @param local
     *            本地存储文件的完整路径
     * @throws UncorrectedRemotePathException
     *             当远程路径不存在是抛出此异常
     */
    void download(String remote, String local);

    /**
     * 下载远程服务器上的文件，并存储到本地.
     * 
     * <pre>
     * remote 如果是文件夹则将对文件夹中的文件进行filter过滤，将符合filter的文件下载；
     * 如果local 是文件名则使用locl 如果local 是路径则使用服务器文件名；
     * 过滤规则： 远程文件命中包含filter字符串。
     * tips： 文件夹必须包含结束字符串，否则认定为文件 。在文件目录中过滤符合名称的文件进行下载
     * </pre>
     * 
     * @param remote
     *            远程FTP服务器文件的完整路径
     * @param local
     *            本地存储文件的完整路径
     * @param filter
     *            过滤内容
     * @throws UncorrectedRemotePathException
     *             当远程路径不存在是抛出此异常
     */
    void download(String remote, String local, String filter);

    /**
     * 断开连接.
     * 
     * <pre>
     * 下载完成后需手动调用此方法来关闭ftp连接。
     * </pre>
     */
    void disconnect();
}
